---
title: DocumentRange
summary: API reference for DocumentRange.
status: draft
owner: SAIF Doc Gen
last_reviewed: 2026-09-17
library: PdfAPI.Core
reference_type: package
---

# DocumentRange

`DocumentRange` pairs a single `Document` with one or more `PageRange` selections, and is the input to [Extract pages](../../operations/op-08-extract-pages.md) and the per-item payload of `MergeRequest.DocumentRanges`. Its private constructor substitutes a default all-pages `PageRange` whenever the supplied array is null or empty, so a range is never truly empty.

## Purpose
- Associates a `Document` with the specific pages selected from it for extraction or merge operations.
- Guarantees a usable page selection even when none is supplied, by defaulting to all pages. ([BR-30](../../business-rules.md#br-30-empty-page-ranges-default-to-all-pages))
- Renders a human-readable page expression via `ToString()`, used as `PdfResult.Message` after extraction. ([BR-18](../../business-rules.md#br-18-extraction-result-records-processor-and-page-expression))

## Context
- Namespace: `PdfAPI.Core`
- Assembly/package: `PdfAPI.Core`

## Public members
| Member | Signature | Purpose |
| --- | --- | --- |
| Document | `Document Document { get; }` | The document these page ranges apply to. |
| PageRanges | `List<PageRange> PageRanges { get; }` | The page selections to copy from `Document`. |
| DocumentRange(Document, PageRange[]) | `DocumentRange(Document document, params PageRange[] pageRanges)` | Constructs a range directly from a document and an explicit set of page ranges, defaulting to all pages when none are supplied. ([BR-30](../../business-rules.md#br-30-empty-page-ranges-default-to-all-pages)) |
| Create(Document, string) | `static DocumentRange Create(Document document, string pages = "*")` | Builds a range by parsing a page-expression string via [Parse a page expression](../../operations/op-11-parse-a-page-expression.md). |
| Create(Document, PageRange[]) | `static DocumentRange Create(Document document, PageRange[] pageRanges)` | Builds a range from an already-constructed array of page ranges. |
| Dispose() | `void Dispose()` | Disposes the underlying `Document`, deleting its backing file. ([BR-24](../../business-rules.md#br-24-disposing-a-document-deletes-its-file)) |
| ToString() | `override string ToString()` | Renders the page ranges as a comma-joined expression using `SAIF.Common.Extensions.ToStringAll`. |

## Behavioral notes
- Disposing a `DocumentRange` cascades to disposing its `Document`, which deletes the document's backing file. ([BR-24](../../business-rules.md#br-24-disposing-a-document-deletes-its-file))

## Constraints and usage notes
- Prefer `Create(Document, string)` when a caller has a human-authored page expression; use the constructor or `Create(Document, PageRange[])` when ranges are already computed.

## Related documentation
- [Index](../../index.md)
- [Overview](../../overview.md)
- [Architecture](../../architecture.md)
- [Dependencies](../../dependencies.md)
- [Operations and processes](../../operations-processes.md)
- [Business rules](../../business-rules.md)
- [Security and authorization](../../security-authorization.md)
- [API reference](../index.md)

## Sources
- `PdfAPI.Core\Extract\DocumentRange.cs`